Indenting source code
The indent features of Vim are very helpful for indenting source code. This tip discusses settings that affect indentation. For related information, see: *Shifting blocks visually commands to change indents *How to stop auto indenting how to stop your indents from being changed *Restoring indent after typing hash problems when typing # *Toggle auto-indenting for code paste to avoid broken indents when pasting in a terminal Setup Indentation without hard tabs For indentation without tabs, the principle is to set 'expandtab', and set 'shiftwidth' and 'softtabstop' to the same value, while leaving 'tabstop' at its default value: set expandtab set shiftwidth=2 set softtabstop=2 These settings will result in spaces being used for all indentation. Indentation purely with hard tabs For indentation purely with hard tabs, the princible is to set 'tabstop' and 'shiftwidth' to the same value, and to leave 'expandtab' at its default value ('noexpandtab'), and leave 'softtabstop' unset: set shiftwidth=2 set tabstop=2 These settings will result in hard tabs being used for all indentation. Indentation with mixed tabs and spaces For indentation with mixed tabs and spaces, the principle is to set 'shiftwidth' and 'softtabstop' to the same value, leave 'expandtab' at its default ('noexpandtab'). Usually, 'tabstop' is left at its default value: set shiftwidth=2 set softtabstop=2 These settings will cause as many hard tabs as possible being used for indentation, and spaces will be used to fill in the remains. Explanation of the options Vim's different indentation options is an endless source of grief and confusion for new users. There are plenty of example vimrcs out there that will tell you how theirs is the proper setup. More often than not, they are misguided. Let :help be your reference, and this be your guide to Vim's indentation options. *'tabstop' changes the width of the TAB character, plain and simple. *'softtabstop' affects what happens when you press the or keys. Its default value is the same as the value of 'tabstop', but when using indentation without hard tabs or mixed indentation, you want to set it to the same value as 'shiftwidth'. If 'expandtab' is unset, and 'tabstop' is different from 'tabstop', the key will minimize the amount of spaces inserted by using multiples of TAB characters. For instance, if 'tabstop' is 8, and the amount of consecutive space inserted is 20, two TAB characters and four spaces will be used. *'shiftwidth' affects what happens when you press >>, << or . It also affects how automatic indentation works. (See below.) *'expandtab' affects what happens when you press the key. If 'expandtab' is set, pressing the key will always insert 'softtabstop' amount of space characters. Otherwise, the amount of spaces inserted is minimized by using TAB characters. *'smarttab' affects how key presses are interpreted depending on where the cursor is. If 'smarttab' is on, a key inserts indentation according to 'shiftwidth' at the beginning of the line, whereas 'tabstop' and 'softtabstop' are used elsewhere. There is seldom any need to set this option, unless it is necessary to use hard TAB characters in body text or code. Considerations Using a 'tabstop' value other than the default (8 spaces), will result in your file having a different appearance when using tools such as cat (type on Windows), which can't use a custom width tab character. On the other hand, using hard tabs for indentation, allows others to view your code with the amount of indentation they prefer. Which of these considerations should have priority, is a matter of personal preference (and company policy). Methods for automatic indentation There are a number of methods enabling automatic indentation in Vim, ranging from fairly "stupid" and unintrusive ones, like 'autoindent' and 'smartindent', to complex ones such as 'cindent' and custom indentation based on filetype using 'indentexpr'. The amount of indentation used for one level is controlled by the 'shiftwidth' option. (See above.) 'autoindent' 'autoindent' does nothing more than copy the indentation from the previous line, when starting a new line. It can be useful for structured text files, or when you want to control most of the indentation manually, without Vim interfering. 'autoindent' does not interfere with other indentation settings, and some file type based indentation scripts even enable it automatically. 'smartindent' and 'cindent' 'smartindent' automatically inserts one extra level of indentation in some cases, and works for C-like files. 'cindent' is more customizable, but also more strict when it comes to syntax. 'smartindent' and 'cindent' might interfere with file type based indentation, and should never be used in conjunction with it. When it comes to C and C++, file type based indentations automatically sets 'cindent', and for that reason, there is no need to set 'cindent' manually for such files. In these cases, the 'cinwords', 'cinkeys' and 'cinoptions' options still apply. Generally, 'smartindent' or 'cindent' should only be set manually if you're not satisfied with how file type based indentation works. File type based indentation This type of indentation is the most flexible, as it allows users to customize indentation per file type. For instance, the indentation scripts for C and C++ file types properly set the 'cindent' option, and there are very competent indentation scripts for Ruby, Perl and many other languages and file types. File type based indentation even works correctly with Makefiles without interference! If you plan on using file type based indentation, don't set 'smartindent' or 'cindent'. You may still set 'autoindent', since it doesn't interfere. The vimrc_example.vim that ships with Vim enables filetype based indentation: if has("autocmd") " Enable file type detection. " Use the default filetype settings, so that mail gets 'tw' set to 72, " 'cindent' is on in C files, etc. " Also load indent files, to automatically do language-dependent indenting. filetype plugin indent on " ... endif Indentation in languages using braces :Following needs expansion; it is from an idea now removed from 597. For standard programming languages such as C, file type indentation should be sufficient to provide automatic indentation while you are typing. If you are using an unsupported language using braces, consider adjusting the 'indentkeys' option. * * * :This seems odd. 'indentkeys' only affects indentation using 'indentexpr', which requires a proper indent/filetype.vim file. Is this tip rather about using 'cindent' for unrecognized filetypes? 'smartindent' might be more useful in that case - consider indent/javascript.vim as a discouragement. (Spiiph 00:25, September 2, 2009 (UTC)) ::To assist understanding the origin of this, following is the original tip as proposed for 200903 (which was merged into 597). I think the above is my quick inclusion of Fritzophrenic's comment. Perhaps this whole section should be deleted? Or, if there is some useful point here, it needs to be rewritten because my summary above is not helpful. JohnBeckett 09:04, September 2, 2009 (UTC) Original Whenever you complete a code block in a curly braces language by typing '}', this mapping automatically indents said block. imap } }=%``a It works by typing out the '}', indenting with % and then returning to the last cursor position. It then puts Vim back in insert mode (with a). This doesn't work cleanly if the closing curly brace has to be indented outwards (the cursor goes to where it was originally typed). I don't believe there is a clean way to handle this. ;Comments Why is this mapping needed? Don't the Vim defaults automatically indent C programs as you type, with no need to do anything special when } is pressed? --JohnBeckett 09:08, 28 March 2009 (UTC) :Perhaps this isn't for C code, in which case 'cindent' would not be set and 'cinkeys' would have no effect? 'indentkeys' would still be the correct way to do this, however, as far as I can tell. (:help 'cindent'/'cinkeys'/'indentkeys') --Fritzophrenic 17:28, 30 March 2009 (UTC) :It might be useful for doing something like i{po}, where the pasted text would not be automatically indented. Of course, one should've used ]p instead, but sometimes you forget. I think it's a nice mapping, albeit with limited functionality. (Spiiph 10:22, September 2, 2009 (UTC)) References * * * * * * * * * See also *1231 Set indent parameters for Python files adjust Vim's indent settings to match each file edited (more than Python) *Merge some of following tips. Indenting code *221 Indenting Java throw statements *247 Preexisting code indentation *700 Indenting for Java *909 Easy indenting in insert and normal mode with no cursor displacement *1213 Better indent support for php with html Auto indent *522 Fix an autoindent error *551 Automatically indent an XML file using XSLT Select a block of lines having the same indent *1014 Visual selection of indent block *1269 Indent text object Other *103 Move to next/previous line with same indentation *112 Back and forth between indented lines again *477 Put the indentation level on the status line *1168 Folding for plain text files based on indentation Comments The following should be merged to 224 (or maybe this tip), or deleted: *522 Fix an autoindent error Nice piece of code, but is the content worth keeping? I do not know what scenario it describes or what it achieves. JohnBeckett 10:06, 12 August 2009 (UTC)